文档首页

新手指南

API参考手册

SDK

工具

技术文章

Ruby SDK 使用指南

概述

此 Ruby SDK 适用于 Ruby 1.9.x，2.0.x，2.1.x，jruby，rbx，ree 版本，基于 七牛云存储官方API 构建。使用此 SDK 构建您的网络应用程序，能让您以非常便捷的方式将数据安全地存放到七牛云存储上。无论您开发的是一个网站，还是基于“云端（服务端程序）－终端（手持设备应用）架构”的服务或应用，借助七牛云存储及其SDK，都能让该应用的终端用户高速上传和下载，同时也让您的服务端更加轻盈。

■ 参考链接

源码地址：https://github.com/qiniu/ruby-sdk
打包下载：https://github.com/qiniu/ruby-sdk/archive/master.zip
历史版本：https://github.com/qiniu/ruby-sdk/releases

■ 状态

集成测试：Build Status
Gem发布：Gem Version
依赖关系：Dependency Status
代码评分：Code Climate

■ 维护人员

liangtao@qiniu.com（@无锋之刃）

准备开发环境

■ 通过 bundle 工具安装

  1. 在您 Ruby 应用程序的 Gemfile 文件中，添加如下一行代码：

    gem 'qiniu', '~> 6.2.1'

  2. 然后，在应用程序所在的目录下，可以运行 bundle 安装依赖包：

    $ bundle

■ 直接安装 Gem 包

$ gem install qiniu

■ ACCESS_KEY 和 SECRET_KEY

在使用SDK 前，您需要拥有一对有效的 AccessKey 和 SecretKey 用来进行签名授权。

可以通过如下步骤获得：

  1. 开通七牛开发者帐号
  2. 登录七牛开发者平台，查看 AccessKey 和 SecretKey

注意：用户应当妥善保存SECRET_KEY，不能对外泄露（尤其不能放置在客户端中，并分发给最终用户）。一旦发生泄露，请立刻到开发者平台更新。

使用SDK

■ 初始化环境

在使用Ruby SDK之前，需要初始化环境，并且设置默认的ACCESS_KEY和SECRET_KEY：

#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! :access_key => '<YOUR_APP_ACCESS_KEY>',
                            :secret_key => '<YOUR_APP_SECRET_KEY>'

如果您使用的是 Ruby on Rails 框架，我们建议您在应用初始化启动的过程中，调用上述方法即可，操作如下：

  1. 首先，在应用初始化脚本加载的目录中新建一个文件：YOUR_RAILS_APP/config/initializers/qiniu_sdk.rb

  2. 然后，编辑 YOUR_RAILS_APP/config/initializers/qiniu_sdk.rb 文件内容如下：

#!/usr/bin/env ruby

require 'qiniu'

Qiniu.establish_connection! :access_key => '<YOUR_APP_ACCESS_KEY>',
                            :secret_key => '<YOUR_APP_SECRET_KEY>'

这样，您就可以在您的 RAILS_APP 中使用七牛云存储 Ruby SDK 提供的其他任意方法了。

■ 上传文件

为了尽可能地改善终端用户的上传体验，七牛云存储首创了客户端直传功能。一般云存储的上传流程是：

客户端（终端用户） ==上传==> 业务服务器 ==上传==> 云存储服务

这样多了一次上传的流程，和本地存储相比，会相对慢一些。为减少上传浆糊，七牛引入“客户端直传”概念，将整个上传过程调整为：

客户端（终端用户） ==上传==> 七牛云存储 ==通知==> 业务服务器

客户端（终端用户）直接将文件上传到七牛服务器。这一过程中，七牛会通过DNS智能解析，为客户端选择到传输距离最近的运营商节点，速度会比本地存储快很多。
文件上传成功以后，七牛服务器通过回调功能，将少量元数据（比如Key、文件元信息或开发者自定义变量）传给业务服务器，再由业务服务器按业务逻辑处理即可。

□ 上传流程

在七牛云存储中，整个上传流程大体分为如下几步：

  1. 业务服务器颁发 uptoken（上传凭证，下同） 给客户端（终端用户）；
  2. 客户端凭借 uptoken 上传文件到七牛云存储；
  3. 在七牛云存储收存完整数据后，发起一个 HTTP 请求，回调业务服务器预设的通知接收接口；
  4. 业务服务器处理上传通知，保存相关业务信息，并返回一些响应信息给七牛云存储；
  5. 七牛云存储将响应信息（含HTTP响应码）原封不动地转发给客户端（终端用户）。

请注意“回调业务服务器”这一行为是可选的，执行与否取决于业务服务器使用的上传策略。如果未设置回调，七牛云存储会将一些标准的信息（比如文件的 hash）返回给客户端。

如果上传发生在业务服务器，以上流程可以简化为：

  1. 业务服务器生成 uptoken（不设置回调，自己回调到自己这里没有意义）；
  2. 凭借 uptoken 上传文件到七牛；
  3. 善后工作，比如保存相关的元信息。

□ 上传策略

uptoken本质上是用 AccessKey/SecretKey 进行数字签名的上传策略，它控制着整个上传流程的行为。让我们快速过一遍都能够决策啥：

module Qiniu
  module Auth
    class PutPolicy
      PARAMS = {
        # 字符串类型参数
        :scope                  => "scope"               ,
        :save_key               => "saveKey"             ,
        :end_user               => "endUser"             ,
        :return_url             => "returnUrl"           ,
        :return_body            => "returnBody"          ,
        :callback_url           => "callbackUrl"         ,
        :callback_body          => "callbackBody"        ,
        :persistent_ops         => "persistentOps"       ,
        :persistent_notify_url  => "persistentNotifyUrl" ,

        # 数值类型参数
        :deadline               => "deadline"            ,
        :insert_only            => "insertOnly"          ,
        :fsize_limit            => "fsizeLimit"          ,
        :detect_mime            => "detectMime"          ,
        :mime_limit             => "mimeLimit"
      } # PARAMS
    end # class PutPolicy
  end # module Auth
end # module Qiniu

更完整的说明请参考上传策略。

□ 生成上传凭证

服务端生成 uptoken 的示例代码如下：

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

put_policy = Qiniu::Auth::PutPolicy.new(
    bucket,     # 存储空间
    key,        # 最终资源名，可省略，即缺省为“创建”语义
    expires_in, # 相对有效期，可省略，缺省为3600秒后 uptoken 过期
    deadline    # 绝对有效期，可省略，指明 uptoken 过期期限（绝对值），通常用于调试
)

uptoken = Qiniu::Auth.generate_uptoken(put_policy)

□ 上传文件

上传文件到七牛（通常是客户端完成，但也可以发生在服务端）：

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法
# 已生成一个有效的put_policy，参考前文

code, result, response_headers = Qiniu::Storage.upload_with_put_policy(
    put_policy,     # 上传策略
    local_file,     # 本地文件名
    key,            # 最终资源名，可省略，缺省为上传策略 scope 字段中指定的Key值
    x_var           # 用户自定义变量，可省略，需要指定为一个 Hash 对象
)

■ 下载文件

□ 下载公有文件

每个 bucket 都会绑定一个或多个域名（domain）。如果这个 bucket 是公开的，那么该 bucket 中的任意资源都可以通过对应的公开下载 url 访问到：

http://<domain>/<key>

假设某个 bucket 既绑定了七牛的二级域名，如 hello.qiniudn.com，也绑定了自定义域名（需要备案），如 hello.com。那么该 bucket 中 key 为 a/b/c.htm 的资源可以通过http://hello.qiniudn.com/a/b/c.htm或http://hello.com/a/b/c.htm进行访问。

注意： key必须采用utf8编码，如使用非utf8编码访问七牛云存储将反馈错误

□ 下载私有文件

如果某个 bucket 是私有的，那么这个 bucket 中的所有文件只能通过一个的临时有效的下载 url 访问：

http://<domain>/<key>?e=<deadline>&token=<dntoken>

其中 dntoken 是由业务服务器签发的一个临时下载授权凭证，deadline 是 dntoken 的有效期。dntoken不需要单独生成，SDK 提供了生成完整下载 url 的方法（包含了 dntoken），示例代码如下：

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

primitive_url = 'http://hello.qiniudn.com/a/b/c.htm'
download_url = Qiniu::Auth.authorize_download_url(primitive_url)

生成下载 url 后，业务服务器将其下发给客户端。客户端收到下载 url 后，直接用任意 HTTP 客户端即可下载该资源（与下载公有资源无异）。
唯一需要注意的是，在下载 url 已失效却还没有完成下载时，需要重新向业务服务器申请授权。

无论公有资源还是私有资源，下载过程中客户端并不需要七牛 SDK 参与其中。

□ 断点续下载

无论是公有资源还是私有资源，获得的下载 url 支持标准的 HTTP 断点续传协议。考虑到多数语言都有相应的断点续下载支持的成熟方法，七牛 Ruby-SDK 并不提供断点续下载相关代码。

■ 资源操作

资源操作包括对存储在七牛云存储上的文件进行查看、复制、移动和删除处理，并且允许批量地执行文件管理操作，方便用户使用。

□ 获取文件信息

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

code, result, response_headers = Qiniu::Storage.stat(
    bucket,     # 存储空间
    key         # 资源名
)

□ 删除文件

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

code, result, response_headers = Qiniu::Storage.delete(
    bucket,     # 存储空间
    key         # 资源名
)

□ 复制文件

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

code, result, response_headers = Qiniu::Storage.copy(
    src_bucket,     # 源存储空间
    src_key,        # 源资源名
    dst_bucket,     # 目标存储空间
    dst_key         # 目标资源名
)

□ 移动文件

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用Qiniu#establish_connection!方法

code, result, response_headers = Qiniu::Storage.move(
    src_bucket,     # 源存储空间
    src_key,        # 源资源名
    dst_bucket,     # 目标存储空间
    dst_key         # 目标资源名
)

错误报告

如果遇到错误，请将各个方法返回的code、result、response_headers以如下方法格式化输出，并将输出结果通过邮件发送给我们。

#!/usr/bin/env ruby

require 'qiniu'

# 已在某处调用某个SDK方法

puts code.inspect
puts result.inspect
puts response_headers.inspect

贡献代码

  1. Fork；
  2. 创建您的特性分支 (git checkout -b my-new-feature)；
  3. 提交您的改动 (git commit -am ‘Added some feature’)；
  4. 将您的修改记录提交到远程 git 仓库 (git push origin my-new-feature)；
  5. 然后到 github 网站的该 git 远程仓库的 my-new-feature 分支下发起 Pull Request。

许可证

Copyright © 2014 qiniu.com

基于 MIT 协议发布

如果有任何问题，请进入 七牛云存储问答社区 或者发送 工单 咨询